7.4 PR 清单

用户可以通过GitHub pull requests 的形式向Deis提交变更。

请确保你的 PR 遵循以下清单：

  1. 单个问题
  2. 包含测试
  3. 包含文档
  4. 代码标准
  5. 提交方式

单个问题

当 fix 或执行一个 GitHub issue 的时候，抵住重构附近代码或 fix 你注意到的潜在的 bug 的诱惑。而是仅仅只为本次变更创建一个新的 pull request。

当一个 PR 不专注的时候，很难在价值上达成一致。保持关注点独立可以使得 pull requests 被更快的测试，reviewed，和合并。

Squash 和 rebase commit 或 commit 你的 pull request 转换成 git 逻辑工作单元。在同一个提交中包含测试和文档变更，因此恢复操作将这个特性的所有追踪或 fix。

大部分的 pull requests 将与一个 GitHub issue 相关联，在 PR 描述 - 不是 commit 它自己 - 包含一行如“Closes #1234。” 当你的 PR 被合并的时候，issue 将被关闭。

包含测试

如果你变更或添加功能到任何 Deis 代码，你的变更应该包含必需的测试来证明它是能正常工作的。单元测试可以使用组件实现的语言编写（通常是 Go 或 Python），并且功能和集成测试是使用 Go 编写。测试代码可以在 Deis 项目的 tests/ 目录发现。

当工作期间在当地修改代码的时候，请一直运行测试。确保在提交一个PR之前，你提的变更在你的工作环境通过了 ./tests/bin/test-integration 的所有测试。

查看测试 Deis 获取更多信息。

包含文档

对 Deis 的任何变更都可能影响一个用户的体验也需要变更或者是额外的相关文档。Deis 从在 docs/ 目录的文本标记来源生成 HTML 的文档，托管在 http://docs.deis.io/。

在代码中查看 docs/README.md 获取更多信息。

代码标准

Deis 是一个 Go 和 Python 的项目。对于这两门语言，我们同意 The Zen of Python，其强调 simple over clever。可读性计数。

Go 代码应该一直通过在默认设置上的 gofmt 运行。每行代码应该 99 字符的长度。文档字符串和测试是被要求为公有方法。使用第三方的 go 包应该最小化，但当这样做，在 Deis 包中的 vendor 代码要需要 godep 工具。

Python 代码应该一直坚持 PEP8，Python 代码风格指南，行代码超过 99 字符抛出一个 exception。Docstrings 和 测试被要求为公有方法，尽管被 Deis 使用的 flake8 工具不强迫要求这样做。

设计提议

当考虑一个设计提议的时候，我们寻找的是：

  • 该设计提议解决的问题的描述。
  • 一个修改文档的 pull request，描述你提交的特性。
  • 用提议（在标题） Prefix 你的 pull request。
  • 在报告一个新的之前，请 review 已经存在的提议。

提交方式

git commit 消息必须遵循以下格式：

  1. {type}({scope}): {subject}
  2. <BLANK LINE>
  3. {body}
  4. <BLANK LINE>
  5. {footer}

例如：

  1. feat(logger): add frobnitz pipeline spout discovery
  3. Introduces a FPSD component compatible with the industry standard for
  4. spout discovery.
  6. BREAKING CHANGE: Fixing the buffer overflow in the master subroutine
  7.     required losing compatibility with the UVEX-9. Any UVEX-9 or
  8.     umVEX-8 series artifacts will need to be updated to umVX format
  9.     with the consortium or vendor toolset.

标题行

一个提交消息的第一行是它的标题。它包含了这个变更的主要描述，不超过 50 字符。

{types} 被允许是：

  • feat -> feature
  • fix -> bug fix
  • docs -> documentation
  • style -> formatting
  • ref -> refactoring code
  • test -> adding missing tests
  • chore -> maintenance

{scope} 指定了变更的位置，比如“controller”，“Dockerfiles”，或者是 “.gitignore”。{subject} 应该使用命令的，现在式时态：“change”，不是“changes”或“changed”，不要大写这个动词，或在标题行的最后加一个句号。

消息体

单独的消息体与标题直接有一行空行。body 每行最多 72 个字符。它包含该变更的动机，指出了与先前行为的不同。body 和 footer 应该以完整句的形式写。

消息页脚

单独的页脚与消息体直接有一行空行。提及任何认为有理和迁移注意事项的重大变更。如果变更不能被 Deis 的测试脚本测试，包含指定的用于手工测试的操作指南。

合并的批准

Deis 维护者添加“LGTM”（Looks Good To Me）或者一个相当的评论来指出一个 PR 是可接受的。任何代码变更 - 不仅是一个简单的类型 fix 或一行文档变更 - 要求至少两个维护者接受它。

如果 PR 是来至于一个 Deis 维护者，这时他或她应该是关闭者之一。这可以保持 commit 流干净以及给维护者在是否决定合并这个变更之前重新访问 PR 的权益。